//  INotifier.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  INotifier接口定义了PureMVC框架中的通知发送者行为。
//  它提供了发送通知的方法，使实现类无需直接构造Notification实例。
//  MacroCommand、Command、Mediator和Proxy等类都实现了此接口。
//

#if !defined(__PUREMVC_INTERFACES_INOTIFIER_HPP__)
#define __PUREMVC_INTERFACES_INOTIFIER_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

namespace PureMVC
{
    namespace Interfaces
    {
        /**
             * PureMVC通知发送者的接口定义
             * The interface definition for a PureMVC Notifier.
             *
             * <P>
             * <code>MacroCommand、Command、Mediator</code>和<code>Proxy</code>
             * 都需要发送<code>Notifications</code>。
             * <code>MacroCommand, Command, Mediator</code> and <code>Proxy</code>
             * all have a need to send <code>Notifications</code>. </P>
             *
             * <P>
             * <code>INotifier</code>接口提供了一个名为<code>sendNotification</code>的通用方法，
             * 它使实现代码无需实际构造<code>Notifications</code>。
             * The <code>INotifier</code> interface provides a common method called
             * <code>sendNotification</code> that relieves implementation code of
             * the necessity to actually construct <code>Notifications</code>.</P>
             *
             * <P>
             * 所有上述类都扩展的<code>Notifier</code>类还提供了对<code>Facade</code>单例的初始化引用，
             * 这是发送<code>Notifications</code>的便捷方法所必需的，
             * 但也简化了实现，因为这些类频繁与<code>Facade</code>交互，通常无论如何都需要访问facade。
             * The <code>Notifier</code> class, which all of the above mentioned classes
             * extend, also provides an initialized reference to the <code>Facade</code>
             * Singleton, which is required for the convienience method
             * for sending <code>Notifications</code>, but also eases implementation as these
             * classes have frequent <code>Facade</code> interactions and usually require
             * access to the facade anyway.</P>
             *
             * @see Interfaces/IFacade.hpp PureMVC::Interfaces::IFacade
             * @see Interfaces/INotification.hpp PureMVC::Interfaces::INotification
             */

            struct PUREMVC_API INotifier
        {
            /**
                 * 发送一个<code>INotification</code>
                 * Send a <code>INotification</code>.
                 *
                 * <P>
                 * 便捷方法，避免在实现代码中构造新的通知实例
                 * Convenience method to prevent having to construct new
                 * notification instances in our implementation code.</P>
                 *
                 * @param notification_name 要发送的通知名称
                 * @param body 通知的主体内容（可选）
                 * @param type 通知的类型（可选）
                 */
                virtual void sendNotification(std::string const& notification_name, void const* body = NULL, std::string const& type = "") = 0;

            /**
                 * 初始化此INotifier实例
                 * Initialize this INotifier instance.
                 * <P>
                 * 这是Notifier获取其multitonKey的方式。
                 * 在调用此方法之前，调用sendNotification或访问facade将失败。
                 * This is how a Notifier gets its multitonKey.
                 * Calls to sendNotification or to access the
                 * facade will fail until after this method
                 * has been called.</P>
                 *
                 * @param key 此INotifier要使用的multitonKey
                 */
                virtual void initializeNotifier(std::string const& key) = 0;

            /**
                 * 获取multiton键
                 * Get multiton key.
                 *
                 * @return 通知者的键
                 */
                virtual std::string const& getMultitonKey(void) const = 0;

            /**
                 * 虚析构函数
                 * Virtual destructor.
                 */
                virtual ~INotifier(void);
        };
    }
}

#endif /* __PUREMVC_INTERFACES_INOTIFIER_HPP__ */
